home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / basic / pbasmlib.zip / MISC.DOC < prev    next >
Text File  |  1994-02-12  |  12KB  |  269 lines
  1. PBASMLIB Assembly Language Routines for PB3C
  2. Version 1.0
  3. Miscellaneous Routines Module
  4. (C) Copyright 1994 by Tim Gerchmez
  5. All Rights Reserved.
  6.  
  7. This module contains miscellaneous routines.  It will be immediately
  8. accessible to your programs by adding the statements $INCLUDE "PBASMLIB.INC"
  9. and $LINK "PBASMLIB.PBL" at the top of your programs.  It's recommended
  10. that you use these routines only in a standalone .EXE file, since they
  11. include several interrupt-driven routines which should not be repeatedly
  12. stopped and restarted with IDE compiles.  There is a possibility of
  13. interrupt vectors being corrupted if these routines are used in the
  14. PowerBASIC IDE environment.
  15.  
  16. ================================================================================
  17. function countflag
  18.  
  19. Used in conjunction with the PBASMLIB COUNTDOWN timer to check
  20. when countdown is finished.  COUNTFLAG will return -1 when countdown
  21. is complete, or 0 if COUNTDOWN is still progressing.  Countflag will
  22. not be reset to zero until COUNTDOWN is started again.
  23.  
  24. Example: print countflag
  25.  
  26. ================================================================================
  27. function countval
  28.  
  29. Returns the time remaining for the countdown timer COUNTDOWN.
  30. It will return the number of timer ticks left (18.2 per second)
  31. until the countdown timer completes its countdown.
  32.  
  33. Example: print countval
  34.  
  35. ================================================================================
  36. sub countdown(t??)
  37.  
  38. Sets and activates a "countdown timer" that can be checked
  39. with COUNTFLAG or used in conjunction with ON UEVENT to branch
  40. to a subroutine when the countdown completes.  When the countdown
  41. completes, the "countdown timer" will have to be reset with this
  42. routine again if another countdown needs to be done.  A countdown can
  43. also be interrupted in the middle and restarted using any value desired
  44. by simply issuing this command again.  Note: Unlike some of the other
  45. routines in PBASMLIB's MISC module, countdown WILL work in the IDE just fine.
  46.  
  47. t??: Set to number of "timer ticks."  Each timer tick is 1/18.2 of
  48.      a second.  When the countdown completes, a flag will be set that
  49.      you can check with COUNTFLAG, or you can use UEVENT to automatically
  50.      interrupt your program (see example below, and the PB manuals).
  51.  
  52. Example: on uevent gosub counted    'UEVENT is a PowerBASIC command
  53.          uevent on                  'Turn UEVENT checking on.
  54.          countdown 18.2*5           'Set countdown timer for 5 seconds
  55.          do:loop                    'Go into an endless (actually 5-second) loop
  56.          counted:
  57.             print "UEVENT HAPPENED!":end
  58.  
  59. Example: countdown 36.4 '2-second countdown
  60.          do
  61.         loop until countflag  'Use COUNTFLAG function
  62.          print "countdown complete."
  63.  
  64. ================================================================================
  65. function alarmcheck
  66.  
  67. Checks the status of the CMOS alarm set with ALARMSET.
  68. Returns zero if alarm has not gone off, or -1 if alarm has
  69. gone off.  The ALARMCHECK flag will stay at -1 after the alarm
  70. has gone off, until alarm is reset with the ALARMSET procedure,
  71. or turned off with ALARMCLEAR.  You can use ON UEVENT instead of
  72. alarmcheck to cause your program to branch to a subroutine when the
  73. alarm goes off.
  74.  
  75. Example: if alarmcheck then print "Alarm went off."
  76.  
  77. ================================================================================
  78. sub alarmclear
  79.  
  80. Clears any pending alarm request on the CMOS time/date chip
  81. (see ALARMSET).  Use to cancel ALARMSET at the end of your
  82. PowerBASIC program, if the alarm hasn't gone off by the time
  83. your program ends (if it has, calling this routine won't do any
  84. harm).  Note that the alarm is cleared or turned off automatically
  85. when it "rings" - you must call ALARMSET again to restart it after
  86. it has gone off.
  87.  
  88. Example: call alarmclear
  89.  
  90. ================================================================================
  91. sub alarmset(hr%,mn%,sc%)
  92.  
  93. Sets an interrupt-level alarm clock in the CMOS time/date chip that
  94. can be checked at any time during the program with ALARMCHECK, or can
  95. be trapped with ON UEVENT.  Only one alarm may be active at any given time.
  96. When the alarm goes off, a flag will be set which you can check with ALARMCHECK.
  97. You can also use ON UEVENT GOSUB and UEVENT ON to make your program branch to a
  98. particular place when the alarm goes off (see example below).  Be sure to use
  99. ALARMCLEAR at the end of your program to turn off the alarm if the program ends
  100. before the alarm goes off, or a system crash will occur after the program exits
  101. to DOS and the alarm finally goes off.  ALARMCLEAR is called automatically when
  102. the alarm goes off, so you'll have to call this routine again to reactivate the alarm.
  103.  
  104. Note: I've found that for some reason this routine will
  105.       not work in the PB IDE.  An alarm can only be set
  106.       and activated from a standalone .EXE program.
  107.  
  108. hr%: Set to hour (0-23) - Military (24-Hr.) time
  109. mn%: Set to minutes (0-59)
  110. sc%: Set to seconds (0-59)
  111.  
  112. Example: alarmset 0,0,0 'Set to midnight exactly
  113.          do
  114.             if alarmcheck then
  115.                 print "Midnight!":beep  'See ALARMCHECK
  116.                     end
  117.             end if
  118.         loop                              'Waits til midnight
  119.  
  120. Example: on uevent gosub alarmrang  'GOSUB to alarmrang when alarm goes off
  121.          uevent on         'Turn on UEVENT trapping
  122.          alarmset 0,0,0    'Set to midnight
  123.          'Continue your program here, the subroutine you
  124.          'specified in ON UEVENT will be called at alarm time.
  125.  
  126.  
  127. ================================================================================
  128. function checkbreak
  129.  
  130. Works in conjunction with the FAILSAFE command to return a flag
  131. indicating whether the user attempted to break out of a program.
  132. Returns 0 if not, 1 if user pressed CTRL-BREAK, or 2 if user pressed
  133. CTRL-ALT-DEL.  Using CHECKBREAK sets the flag to zero, so assign CHECKBREAK
  134. to a variable if you need to save the status of the flag.
  135.  
  136. Example: cb% = checkbreak
  137.  
  138. ================================================================================
  139. sub coldboot
  140.  
  141. Calling this routine will perform a cold boot, resetting
  142. the computer.  This routine is optimized to reboot the computer
  143. in just about all situations, including multitasking and protected
  144. mode environments like Desqview or Windows.  Use with caution, and
  145. make sure all files are closed and data is flushed before calling this
  146. routine, or data loss may occur (Caution: data loss may occur when using
  147. this routine with delayed writeback disk cache programs).  You use this
  148. routine entirely at your own risk and the risk of the users of your programs.
  149.  
  150. Example: call coldboot
  151.  
  152. ================================================================================
  153. sub failsafe(ed%)
  154.  
  155. Executes a routine that traps the CTRL-C, CTRL-BREAK and
  156. CTRL-ALT-DEL key combinations.  This makes your program
  157. "failsafe" in that it can't be terminated by any of these keys,
  158. or rebooted by the user at the wrong time.  It also prevents the
  159. infamous PB3 "CTRL-BREAK" problem, where sometimes a PowerBASIC
  160. program will exit to DOS after CTRL-BREAK is pressed without resetting
  161. interrupt vectors - a sure guarantee of a system crash.  Note: BE SURE
  162. TO TURN FAILSAFE OFF WITH FAILSAFE 0 BEFORE ENDING YOUR PROGRAM, OR A
  163. SYSTEM CRASH WILL OCCUR WHEN THE USER EXITS TO DOS!!  Also, FAILSAFE has
  164. no effect while in the PB IDE, and works only in a standalone .EXE file.
  165.  
  166. ed%: Set to 1 or 0.  A one turns failsafe mode on, and a zero
  167.      turns failsafe mode off.  Turning failsafe mode on also activates
  168.      the CHECKBREAK function to check if the user attempted to break out of
  169.      the program (see CHECKBREAK).
  170.  
  171. Example: failsafe 1  'Make your program "failsafe"
  172.  
  173. ================================================================================
  174. sub micropause(us&)
  175.  
  176. Pauses for a specified number of microseconds (one
  177. millionth of a second).  This routine isn't perfectly
  178. accurate, as it takes a few microseconds for BASIC to call
  179. the routine, but it does allow a finer resolution than MILLIPAUSE.
  180.  
  181. us&: Set to number of microseconds to pause (1 million = 1 second).
  182.      Max. value that can be passed in a long int is a little over two
  183.      million, or about two seconds max delay with this routine.
  184.  
  185. Example: micropause 10  'Pause 10 microseconds (more or less)
  186.  
  187. ================================================================================
  188. sub millipause(ms%)
  189.  
  190. Pauses for the specified number of milliseconds (1/1000 of
  191. a second.  For finer resolution, use micropause, which pauses for
  192. multiples of 1/1,000,000 of a second.
  193.  
  194. ms%: Set to milliseconds to pause
  195.  
  196. Example: millipause 250  'Pause 250 ms, or 1/4 of a second
  197.  
  198. ================================================================================
  199. sub pbasound(p%,d%)
  200.  
  201. Similar to PowerBASIC's SOUND statement, but does not pull in the
  202. floating point library (which can add 17-20K to your programs if needed
  203. only for the SOUND statement), and has a higher delay resolution than the
  204. SOUND statement (milliseconds).  Also, PBASOUND will not allow your program
  205. to continue until the tone is finished sounding (unlike PB's SOUND statement).
  206. To cancel a tone that is "stuck" on after pressing CTRL-BREAK, execute a
  207. PBASOUND statement with a duration or frequency of zero.
  208.  
  209. p%: Set to frequency value in hertz (37-32767)
  210. d%: Set to milliseconds to delay (a millisecond is 1/1000 of a second).
  211.     The maximum length of time you can sound a tone with PBASOUND is 32767
  212.     milliseconds, or about 32 seconds.  To sound longer tones, execute multiple
  213.     PBASOUND statements.
  214.  
  215. Example: pbasound 250,500  '250 hz. tone 1/2 second long
  216.  
  217. ================================================================================
  218. sub softlockup
  219.  
  220. Locks up the processor, creating a temporary condition that
  221. can be reset with CTRL-ALT-DEL.  This routine is mostly harmless and does
  222. not affect background processes (to my knowledge) such as disk caches,
  223. etc.  Use with caution, however, as there won't be too many situations
  224. where you'll want to intentionally cause a lockup.  For a "hard" lockup,
  225. see HARDLOCKUP.
  226.  
  227. Example: call softlockup
  228.  
  229. ================================================================================
  230. sub hardlockup
  231.  
  232. Locks up the processor, creating a permanent condition that
  233. can only be overcome by powering down/back up or pressing the reset
  234. button.  CTRL-ALT-DEL will have no effect.  Use this routine with
  235. extreme caution, as it halts the processor and can affect background
  236. processes such as lazy-write disk caches, etc.  Data loss may occur
  237. if the CPU is locked up while files are still open, etc.  This routine
  238. will have an unpredictable effect in a multitasking environment.
  239.  
  240. Example: call hardlockup
  241.  
  242. ================================================================================
  243. sub keyboardlock(l%)
  244.  
  245. Allows you to lock (disable) and unlock access to the
  246. keyboard.  Keypresses will be "stored up" in the keyboard
  247. controller while the keyboard is locked, and released when
  248. unlocked (including CTRL-ALT-DEL, etc).  You can clear the
  249. keyboard buffer after unlocking the keyboard, if desired.
  250.  
  251. l%: Set to 1 to lock the keyboard, or 0 to unlock the keyboard
  252.  
  253. Example: keyboardlock 1  'Keyboard is "locked up" until called again with 0
  254.  
  255. ================================================================================
  256. sub warmboot
  257.  
  258. Performs a warm reboot, resetting your computer like CTRL-ALT-DEL had
  259. been pressed (skips the power-up memory test).  Use COLDBOOT to perform a
  260. cold reboot instead if desired (similar to pressing the reset button or
  261. powering off/back on).  This routine is optimized to reboot the computer
  262. in just about all situations, including in multitasking environments.  Use
  263. with extreme caution, making sure all data is flushed to disk and files are
  264. closed.  You use this routine entirely at your own (and your program's user's)
  265. risk.
  266.  
  267. Example: call warmboot
  268.  
  269.